home *** CD-ROM | disk | FTP | other *** search
/ Atari Forever 4 / Atari Forever 4.zip / Atari Forever 4.iso / PD_THEMA / CPX / CLIPBORD / SCRAP2.TXT < prev   
Text File  |  1998-03-14  |  11KB  |  240 lines
  1. ****************************************
  2. The following article first appeared in
  3. the June-July 1991 ATARI.RSC newsletter.
  4. It is being included in this Archive
  5. with the permission of Atari Corp.
  6. ****************************************
  7.  
  8. Using the GEM AES Scrap Library, TAKE TWO
  9. By Mike Fulton, Atari Computer
  10. -----------------------------------------
  11.  
  12. The GEM AES Scrap Library provides a standard method of allowing data
  13. interchange between applications via a clipboard mechanism.  At the user's
  14. request, the current application will place data from its own document onto
  15. the clipboard.  Later, from the same application or a completely different
  16. one, when the user requests the data from the clipboard, it can be read
  17. back into the current document.  There are two GEM AES scrap library
  18. functions, scrp_read() and scrp_write().
  19.  
  20. The Clipboard Manager XCONTROL panel module allows the user to set the
  21. system's clipboard folder to whatever they want, so that this folder will
  22. be specified when the system is booted.  The Clipboard Manager CPX is
  23. documented separately from this article.
  24.  
  25.  
  26. Writing a Clipboard Item
  27. ------------------------
  28.  
  29. WORD sc_wreturn = scrp_write(sc_wpscrap);
  30.  
  31. The scrp_write() call establishes the directory used to contain clipboard
  32. scrap files.  A normal sequence of events for an application to put
  33. something in the clipboard would be:
  34.  
  35. 1)  Do a scrp_read() call to determine the location of the system's
  36.     clipboard folder.  If no existing clipboard folder exists, then it is
  37.     recommended that your application create a folder named "CLIPBRD" in
  38.     the root directory of the system's boot drive, and then construct a
  39.     string containing this path specification.
  40.  
  41.     As far as determining the system's boot drive is concerned, if the
  42.     system drive map returned by the BIOS call Drvmap() indicates that
  43.     drive C is available, then you should create the "CLIPBRD" folder on
  44.     that drive.  Otherwise, create the folder on drive A or ask the user
  45.     where to put it.
  46.  
  47.  
  48. 2)  Do not make assumptions about the format of the string you get from
  49.     scrp_read().   Always examine the string and insure that you have a
  50.     valid path specification like "C:\CLIPBRD\", without a file name at the
  51.     end, and ending with a backslash.  Do whatever manipulations are
  52.     required to get the string into that format.  For example, if there is
  53.     a file specification at the end of the string like
  54.     "C:\CLIPBRD\SCRAP.TXT", then find the first character following the
  55.     last backslash in the string and change it to a NULL.  If you get a
  56.     string like "C:\CLIPBRD" without a trailing backslash, then do an
  57.     Fsfirst() call to check if "CLIPBRD" is a subdirectory, and then append
  58.     the backslash to the end.
  59.  
  60.  
  61. 3)  An application should delete any existing scrap files in the clipboard
  62.     directory before writing its own.  This is done in order to prevent any
  63.     possibility of an old scrap file being grabbed by the next application.
  64.     A application may create its own scrp_clear() function for this
  65.     purpose.  A basic example of such a function might be:
  66.  
  67.           void
  68.           scrp_clear( scrappath )
  69.           char *scrappath;
  70.           {
  71.           short err;
  72.           char scrapfile[200], delfile[200];
  73.           DTABUFFER *theDTA;
  74.  
  75.               theDTA = (DTABUFFER *)Fgetdta();
  76.  
  77.               strcpy( scrapfile, scrappath );
  78.               strcat( scrapfile, "SCRAP.*" );
  79.  
  80.               err = Fsfirst( scrapfile, 2 );
  81.               while( ! err )
  82.               {
  83.                   strcpy( delfile, scrappath );
  84.                   strcat( delfile, theDTA->filename );
  85.                   Fdelete( delfile );
  86.                   err = Fsnext();
  87.               }
  88.           }
  89.  
  90.     The DTABUFFER structure, or something similar, should be defined in
  91.     one of your C compiler's include files.  If you cannot find it, the
  92.     definition is given below:
  93.  
  94.          typedef struct dtabuf{
  95.              char    reserved[21];
  96.              char    attribute;
  97.              short   time;
  98.              short   date;
  99.              long    filesize;
  100.              char    filename[14];
  101.          } DTABUFFER;
  102.   
  103.  
  104.     This function would be passed a pointer to a string which contains the
  105.     current clipboard folder specification, as specified and determined in
  106.     steps 1 & 2 above.
  107.  
  108.  
  109. 4)  Create and write your clipboard file, using at least one of the
  110.     standard file formats given below.  Clipboard files should be of the
  111.     form "SCRAP.*" where the filename extension specifies the type of data
  112.     contained within the file.
  113.  
  114.     The following filenames are reserved for the following file formats.
  115.     Additional file formats may be added to the list as they appear.
  116.  
  117.     SCRAP.TXT -- ASCII only text, with a CR/LF at the end of each line
  118.  
  119.     SCRAP.ASC -- ASCII only text, with a CR/LF at the end of each paragraph
  120.  
  121.     SCRAP.RTF -- ASCII only text with formatting specified through the Rich
  122.                  Text Format defined by Microsoft
  123.  
  124.     SCRAP.1WP -- First Word Plus formatted text
  125.  
  126.     SCRAP.WP --- Word Perfect formatted text
  127.  
  128.     SCRAP.GEM -- Standard GEM Metafile Graphics Image
  129.  
  130.     SCRAP.IMG -- Standard GEM Bitmapped Graphics Image
  131.  
  132.     SCRAP.TIF -- Tiff (Tagged Interchange File Format) Graphics Image
  133.  
  134.     SCRAP.IFF -- Interchange File Format (Usually bit-image graphics, but
  135.                  not limited to that.  Locate IFF file format documentation.)
  136.  
  137.     SCRAP.EPS -- Encapsulated Postscript File
  138.  
  139.     SCRAP.CVG -- Calamus Vector Graphic
  140.  
  141.     SCRAP.DIF -- Data Interchange Format - Spreadsheet/Database data
  142.  
  143.     These are not the only types of clipboard files that may be written.
  144.     It is expected that many applications will want to write their own
  145.     specific file format.  In this case, it is hoped that the details of
  146.     the file format are made available so that it can be supported by other
  147.     applications.  In any case, please notify Atari regarding the file
  148.     format(s) and filename extension(s) used by your application.
  149.  
  150.     At a bare minimum, a text-oriented program should always write
  151.     SCRAP.TXT.  A vector graphics-oriented program should always write
  152.     SCRAP.GEM.  And a bitmapped graphics-oriented program should always
  153.     write SCRAP.IMG.  However, where possible, your application should
  154.     write as many formats as it can.
  155.  
  156.     For example, let's say you have a word processor named WRITEIT that
  157.     wants to create SCRAP.WIT clipboard files containing formatted text in
  158.     its own format.  Besides writing the SCRAP.WIT file for its own format,
  159.     it might also write SCRAP.TXT, SCRAP.ASC, SCRAP.RTF, SCRAP.1WP and any
  160.     other text formats that it understands.  It may even write clipboard
  161.     files in formats it knows how to write, but which it doesn't know how
  162.     to read.
  163.  
  164.     Likewise, a graphics program would write clipboard files for all of the
  165.     graphics formats that it understands.  A vector graphics program might
  166.     even write out a bitmapped image for a non-vector graphics program to
  167.     read.
  168.  
  169.     In some cases, depending on the context, it may be appropriate to write
  170.     both text and graphics formats.  For example, if you are in a graphics
  171.     program and the user has selected a text object to copy to the
  172.     clipboard, then the application may want to write a SCRAP.TXT file
  173.     containing the text from that text object.  Or if the user is currently
  174.     editing a text object, and chooses to paste from the clipboard, then it
  175.     would be valid for the graphics program to look for a text clipboard
  176.     file so that it can grab text to put into the text object.
  177.  
  178.  
  179. 5)  If you got a valid clipboard directory from scrp_read() in step 1 and
  180.     no manipulations were necessary in step 2 in order to get the string
  181.     into the correct format, then you are done.
  182.  
  183.  
  184. 6)  If you did not get a directory from scrp_read() and so created the
  185.     "CLIPBRD" folder yourself, or if you had to manipulate the string in
  186.     step 2, then you now need to do a scrp_write() call using the string
  187.     obtained at the end of step 2.
  188.  
  189.  
  190.  
  191.  
  192.  
  193. Reading A Clipboard Item
  194. ------------------------
  195.  
  196. WORD sc_rreturn = scrp_read( sc_rpscrap );
  197.  
  198. The scrp_read() function returns a string containing the clipboard
  199. directory specification.  The sequence of events for an application to read
  200. an item from the clipboard would be:
  201.  
  202. 1)  Do a scrp_read() call to get the clipboard directory.  If scrp_read()
  203.     returns zero, then the clipboard folder has not been set since the
  204.     computer was last reset.  If the return value is non-zero, then the
  205.     clipboard directory specification is returned to you.
  206.  
  207.     Do not skip step 1 because you've already done it once.  All steps must
  208.     be done each time you want to grab something off the clipboard.  Do not
  209.     assume the clipboard directory will not change while your application
  210.     is running.
  211.  
  212.     The scrp_read() function is defined as possibly returning an error code
  213.     of zero. However, this function currently always returns a value of 1.
  214.     Since this may change in future versions of GEM AES, applications
  215.     should handle the case of the error code even if the programmer does
  216.     not expect to see it.
  217.  
  218. 2)  If scrp_read() returns an error code of zero, then the application
  219.     should act as though nothing is available on the clipboard.
  220.  
  221. 3)  If you get a valid string from scrp_read() then you need to make sure
  222.     it is in the correct format as described above in Step 2 of "Writing a
  223.     Clipboard Item".
  224.  
  225. 4)  Now you should have a path specification like "C:\CLIPBRD\".  Now use
  226.     Fsfirst() and Fsnext() to search the clipboard directory for a
  227.     "SCRAP.xxx" file your application understands.  You should first look
  228.     for the formats that will provide the most information and then check
  229.     for more simple formats.  That is, a word processor would want to look
  230.     for SCRAP.1WP before looking for SCRAP.TXT, because the SCRAP.1WP file
  231.     would specify information about formatting and text styles that the
  232.     SCRAP.TXT file would not.
  233.  
  234. 5)  Assuming your application can find a scrap file that it can understand,
  235.     then it should open the scrap file, read in the information it
  236.     contains, insert the information in the the current document as
  237.     appropriate, and then close the scrap file.
  238.  
  239.  
  240.